<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Variable Validation and Policy Help</title>
    <style>
        body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; max-width: 1200px; margin: 0 auto; padding: 20px; line-height: 1.6; }
        .back-link { margin-bottom: 20px; }
        .back-link a { text-decoration: none; color: #007acc; }
        .header { border-bottom: 2px solid #eee; padding-bottom: 20px; margin-bottom: 30px; }
        .section { margin-bottom: 30px; }
        h2 { color: #007acc; margin-top: 30px; }
        h3 { color: #333; margin-top: 25px; }
        code { background: #f1f3f4; padding: 2px 4px; border-radius: 3px; font-family: 'Monaco', monospace; font-size: 14px; }
        pre { background: #f8f9fa; padding: 15px; border-radius: 5px; overflow-x: auto; border-left: 4px solid #007acc; }
        .example { background: #f8f9fa; padding: 10px; border-radius: 3px; margin: 10px 0; }
        .policy-badge { display: inline-block; padding: 2px 6px; border-radius: 3px; font-size: 11px; margin-right: 5px; color: white; }
        .policy-immediate { background: #28a745; }
        .policy-lazy { background: #ffc107; color: #212529; }
        .policy-force { background: #dc3545; }
        .policy-skip { background: #6c757d; }
        .tip { background: #e3f2fd; padding: 15px; border-radius: 5px; border-left: 4px solid #2196f3; margin: 15px 0; }

        /* AsciiDoc admonition blocks (NOTE, TIP, WARNING, etc.) */
        .admonitionblock {
            margin: 1.5em 0;
            padding: 0.4em 0.6em;
            border-left: 4px solid;
            background: #f8f9fa;
            border-radius: 0 4px 4px 0;
        }

        .admonitionblock .title {
            font-weight: bold;
            text-transform: uppercase;
            font-size: 0.85em;
            margin-bottom: 0.25em;
            letter-spacing: 0.5px;
        }

        .admonitionblock .content {
            margin: 0;
        }

        /* Reduce spacing for paragraphs inside admonitions */
        .admonitionblock p {
            margin: 0.25em 0;
        }

        .admonitionblock p:first-child {
            margin-top: 0;
        }

        .admonitionblock p:last-child {
            margin-bottom: 0;
        }

        /* Specific admonition types */
        .admonitionblock.note {
            border-color: #17a2b8;
            background: #d1ecf1;
        }

        .admonitionblock.note .title {
            color: #0c5460;
        }

        .admonitionblock.tip {
            border-color: #28a745;
            background: #d4edda;
        }

        .admonitionblock.tip .title {
            color: #155724;
        }

        .admonitionblock.important {
            border-color: #ffc107;
            background: #fff3cd;
        }

        .admonitionblock.important .title {
            color: #856404;
        }

        .admonitionblock.warning,
        .admonitionblock.caution {
            border-color: #dc3545;
            background: #f8d7da;
        }

        .admonitionblock.warning .title,
        .admonitionblock.caution .title {
            color: #721c24;
        }
    </style>
</head>
<body>
    <div class="back-link">
        <a href="index.html">← Back to Layer Index</a>
    </div>

    <div class="header">
        <h1>Variable Validation and Policy Help</h1>
        <p>Reference for rpi-image-gen layer variable validation rules and set policies.</p>
    </div>

    <div class="section">
        <h2 id="set-policies">Set Policies</h2>
        <p>Set policies determine when and how environment variables are applied during the build process:</p>
        <h3><span class="policy-badge policy-force">force</span> Force</h3>
        <p>Always overwrite existing environment value, regardless of what was set before.</p>
        <h3><span class="policy-badge policy-immediate">immediate</span> Immediate (Default)</h3>
        <p>Set the variable if it is currently unset (first-wins strategy). This is the default behavior.</p>
        <h3><span class="policy-badge policy-lazy">lazy</span> Lazy</h3>
        <p>Applied after all layers are processed (last-wins strategy). Useful for defaults that can be overridden.</p>
        <h3><span class="policy-badge policy-skip">skip</span> Skip</h3>
        <p>Never set the variable. Useful for optional variables or when you want to disable a variable.</p>

        <div class="tip">
            <strong>Policy Aliases:</strong><br>
            <code>true/yes/1/y</code> → immediate<br>
            <code>false/no/0/n</code> → skip
        </div>
    </div>

    <div class="section">
        <h2>Validation Types</h2>
        <h3>Basic Types</h3>
        <div class="example">
            <strong>bool                   - Must be: true/false, 1/0, yes/no, y/n (case insensitive)</strong>
        </div>
        <h3>capacity              </h3>
        <div class="example">
            <strong>capacity               - Storage capacity in binary units (1024-based)</strong>
            <br>BINARY CAPACITY UNITS:
            <br>  capacity must be specified with binary (1024-based) units for storage devices
            <br>    8K / 8KiB    (8 × 1024 bytes = 8,192 bytes)
            <br>    128M / 128MiB (128 × 1024² bytes = 134,217,728 bytes)
            <br>    4G / 4GiB    (4 × 1024³ bytes = 4,294,967,296 bytes)
            <br>    2T / 2TiB    (2 × 1024⁴ bytes)
            <br>  Supported units: K, M, G, T (short form)
            <br>                   KiB, MiB, GiB, TiB (explicit binary)
            <br>  Rejected units:  KB, MB, GB, TB (decimal 1000-based)
            <br>PLAIN NUMBERS (no suffix):
            <br>  Accepted with requirements:
            <br>    Minimum: 512 (typical sector size in bytes)
            <br>    Binary alignment: must be 512, 1024, 2048, 4096, etc.
            <br>  Examples:
            <br>    512
            <br>    4MiB
            <br>    8G
            <br>  This validator is designed for storage device capacity where binary
            <br>  units align with filesystem blocks, sectors, and hardware reality.
        </div>
        <h3>value1,value2,value3 </h3>
        <div class="example">
            <strong>value1,value2,value3  - Must be one of the listed values</strong>
            <br>  (Tip: For a single allowed value, either add a trailing comma
            <br>        e.g. "syft," or use the keywords: prefix as shown below.)
            <br>  Examples:
            <br>    development,staging,production    - Environment names
            <br>    small,medium,large               - Size options
            <br>    debug,info,warn,error            - Log levels
            <br>KEYWORDS:
            <br>  keywords:word1,word2,word3  - Must be one of the listed alphanumeric keywords
            <br>  Keywords can contain: letters (a-z, A-Z), numbers (0-9), underscore (_), hyphen (-)
            <br>  Examples:
            <br>    keywords:frontend,backend,database     - Application components
            <br>    keywords:cpu-intensive,io-bound        - Workload types
            <br>    keywords:dev,test,staging,prod         - Environment shortcuts
        </div>
        <h3>int                   </h3>
        <div class="example">
            <strong>int                    - Must be a valid integer</strong>
            <br>  int:MIN-MAX           - Integer within range (inclusive)
            <br>  Examples:
            <br>    int:1-100           - Integer from 1 to 100
            <br>    int:1024-65535      - Port numbers
            <br>    int:0-255           - Byte values
        </div>
        <h3>regex:PATTERN        </h3>
        <div class="example">
            <strong>regex:PATTERN         - Must match regular expression</strong>
            <br>  Examples:
            <br>    regex:^[a-zA-Z0-9.-]+$     - Hostname format
            <br>    regex:^[0-9]{3}-[0-9]{2}$  - Format like 123-45
            <br>    regex:^(http|https)://     - URLs starting with http/https
        </div>
        <h3>size                  </h3>
        <div class="example">
            <strong>size                   - Size with optional unit (bytes, k/m/g/s) or percentage</strong>
            <br>SIZES:
            <br>  size can be specified in one of the following formats
            <br>    12345        (bytes)
            <br>    20k / 20K    (kilobytes, multiples of 1024)
            <br>    128M / 128m  (megabytes)
            <br>    1G / 4g      (gigabytes)
            <br>    512s         (sectors, multiples of 512)
            <br>    50%          (percentage; any positive integer)
        </div>
        <h3>string                </h3>
        <div class="example">
            <strong>string                 - Must be a non-empty string (required)</strong>
            <br>  string-or-unset        - Must be non-empty string or unset (null)
            <br>  string-or-empty        - Must be any string (may be empty) but not unset
        </div>
    </div>

    <div class="section">
        <h2>Placeholders</h2>
        <p>Auto-substituted in variable values:</p>
        <div class="example">
            <strong><code>${FILENAME}</code></strong> - layer metadata file name<br>
            <strong><code>${DIRECTORY}</code></strong> - directory containing the file<br>
            <strong><code>${FILEPATH}</code></strong> - absolute path to the file<br>
            <em>Escape with <code>\${NAME}</code> to keep the literal text.</em>
        </div>
    </div>

    <div class="section">
        <h2>Example Variable Definitions</h2>
        <pre><code># Port number validation
X-Env-Var-port-Valid: int:1024-65535

# Environment selection
X-Env-Var-env-Valid: development,staging,production

# Hostname validation
X-Env-Var-hostname-Valid: regex:^[a-zA-Z0-9.-]+$

# Boolean flag
X-Env-Var-debug-Valid: bool

# Component selection with keywords
X-Env-Var-component-Valid: keywords:frontend,backend,database</code></pre>
    </div>

    <div class="tip">
        <strong>Testing Tip:</strong> Use <code>rpi-image-gen metadata --lint &lt;file&gt;</code> to quickly check syntax and field names without validating environment variables.
    </div>
</body>
</html>